/*
*  Copyright (c) 2001 Sun Microsystems, Inc.  All rights
*  reserved.
*
*  Redistribution and use in source and binary forms, with or without
*  modification, are permitted provided that the following conditions
*  are met:
*
*  1. Redistributions of source code must retain the above copyright
*  notice, this list of conditions and the following disclaimer.
*
*  2. Redistributions in binary form must reproduce the above copyright
*  notice, this list of conditions and the following disclaimer in
*  the documentation and/or other materials provided with the
*  distribution.
*
*  3. The end-user documentation included with the redistribution,
*  if any, must include the following acknowledgment:
*  "This product includes software developed by the
*  Sun Microsystems, Inc. for Project JXTA."
*  Alternately, this acknowledgment may appear in the software itself,
*  if and wherever such third-party acknowledgments normally appear.
*
*  4. The names "Sun", "Sun Microsystems, Inc.", "JXTA" and "Project JXTA"
*  must not be used to endorse or promote products derived from this
*  software without prior written permission. For written
*  permission, please contact Project JXTA at http://www.jxta.org.
*
*  5. Products derived from this software may not be called "JXTA",
*  nor may "JXTA" appear in their name, without prior written
*  permission of Sun.
*
*  THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
*  WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
*  OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
*  DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
*  ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
*  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
*  LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
*  USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
*  ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
*  OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
*  OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
*  SUCH DAMAGE.
*  ====================================================================
*
*  This software consists of voluntary contributions made by many
*  individuals on behalf of Project JXTA.  For more
*  information on Project JXTA, please see
*  <http://www.jxta.org/>.
*
*  This license is based on the BSD license adopted by the Apache Foundation.
*
*  $Id: PluginContainer.java,v 1.13 2007/03/25 19:17:09 nano Exp $
*/

package net.jxta.myjxta.plugin;

import net.jxta.myjxta.MyJXTA;
import net.jxta.myjxta.util.Group;

import javax.swing.*;
import java.awt.event.MouseEvent;

/**
 *
 * @version $Id: PluginContainer.java,v 1.13 2007/03/25 19:17:09 nano Exp $
 *
 * @author james todd [gonzo at jxta dot org]
 */

public interface PluginContainer {
    void updateGroupState(Group p_group);
    void notifyAboutGroupJoin(Group p_group);
    void notifyAboutGroupResign(Group p_group);
    Plugin[] getPlugins();
    Plugin getPlugin(Class className);

    void destroy();

    MyJXTA getMyJxta();

    /**
     * Selection Provider Interface - every component / plugin that wants to contribute something to the
     * container selection has to implement this interface
     */
    public interface ISelectionProvider{

        /**
         *
         * @return the selected nodes inside the component or <code>null</code> if nothing is selected
         *         or the component isnt active (does not have the focus)
         */
        ISelectableNode[] getSelectedNodes();
    }

    /**
     * Helper Class that represents one PathItem inside the global popup menu
     */
    public final class MenuPath{
        public final String label;
        public final int mnemonic;
        /**
         *
         * @param p_label the label that should be shown inside the menu (menu item text)
         * @param p_mnemonic the mnemonic used for the menu item
         */
        public MenuPath(String p_label, int p_mnemonic)
        {
            label = p_label;
            mnemonic=p_mnemonic;
        }

    }

    /**
     * The popup generator is called from the components that want to contribute to the popup menu
     */
    public interface IPopupGenerator{
        /**
         * adds the given action at the given location to the next shown popup menu
         * @param path array of path elements, each elements represents one menu level,
         *             can be null (action is added at the top level then)
         * @param section the menu section (core, plugins, edit..) used to sort and group the menu path
         *                (not used right now)
         * @param action - the action that should be called if the menu item is selected
         */
        void addPopup(MenuPath[] path,int section,AbstractAction action);
    }

    /**
     * Every component that wants to contribute something to the global popup menu has to implement this interface
     */
    public interface IPopupProvider{
        /**
         *
         * @param popupGenerator  the popup generator (provided by the container) that has to be used to add popup entries
         * @param selectedNodes the current selection at the moment the popup menu was requested - can be empty
         * @param triggerEvent the mouseevent that has triggered the global popup (can be null)
         */
        public void popupRequested(IPopupGenerator popupGenerator,ISelectableNode[] selectedNodes, MouseEvent triggerEvent);
    }

    /**
     *
     * @return the currently selected nodes inside the Container (including all active subcomponents)
     */
    public ISelectableNode[] getSelectedNodes();

    /**
     * Removes the given component from the container selection provider list
     * @param p_component
     */
    void removeSelectionProvider(ISelectionProvider p_component);

    /**
     * adds the given component to the selection provider list
     * every component that is a member of the selection provider list will be asked what nodes are currently
     * selected inside the component if a call to PluginContainer.getSelectedNodes() occurs
     * @param p_component
     */
    void registerSelectionProvider(ISelectionProvider p_component);


    /**
     * registers the given component for popup requests
     * @param p_component
     */
    void registerPopupProvider(IPopupProvider p_component);

    /**
     * removes the given component from the popup request list
     * @param p_component
     */
    void removePopupProvider(IPopupProvider p_component);

    /**
     * triggers the global container popup generation
     * can be called from any component that wants to trigger the popup
     * @param p_selectedNodes the selected nodes that should be the context of the created popup
     * @param p_e the mouse event that has triggered the popup event (used for popup coordinates)
     * @param p_component the JComponent that should be used as the popup parent
     *                    (normaly the JComponent that got the mouse event p_e)
     */
    void triggerGlobalMyJxtaPopup(ISelectableNode[] p_selectedNodes, MouseEvent p_e,JComponent p_component);
    void init();
}
